<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <link href="prettify.css" type="text/css" rel="stylesheet" />
    <link href="styles.css" type="text/css" rel="stylesheet" />
    <script type="text/javascript" src="prettify.js"></script>
    <title>Release process - Noda Time Developer Guide</title>
  </head>
  <body onload="prettyPrint()">
    <div class="header navigation">
      <p class="prev"><a href="coding-conventions.html">Coding conventions</a>&nbsp;</p>
      <p class="next">&nbsp;<a href="tzdb-file-format.html">Time zone database file format</a></p>
      <p class="navtitle">Noda Time Developer Guide</p>
      <div style="clear:both;"></div>
    </div>

    <h1>Release process</h1>
    <p>This document describes how Noda Time is released. It is intended to be used as
a checklist by the person doing a release.</p>

<h2>Prerequisites</h2>

<ul>
<li>Visual Studio 2012</li>
<li>Sandcastle and Sandcastle Help File Builder</li>
<li>NuGet command-line tool</li>
<li>Access to the Noda Time release private key (to produce a strong-named
assembly) and the nuget.org API key</li>
</ul>

<p>Note that we should not build releases on Mono at present, since the resulting
IL triggers a bug in the .NET 4 64-bit CLR (see the
<a href="building.html">building and testing</a> section in the developer guide).</p>

<h2>When to release</h2>

<p>When everybody's happy, there are no issues outstanding for the milestone, and
all the tests pass.</p>

<p>Search the issue tracker for open issues with the right label (e.g.
<code>label:Milestone-1.0</code>).</p>

<p>Update to the candidate revision (probably tip) of the correct branch (e.g.
<code>1.0.x</code>) and <a href="building.html">build and run all the tests</a> as normal. The build
and test steps should pass on Visual Studio 2012 and at least one supported
OS/version combination for Mono (i.e. 'Mono 2.10.9 on Linux').</p>

<h2>Update the embedded tzdb</h2>

<p>If necessary, update the version of tzdb on the branch to the latest current
version, following the instructions in the
<a href="../userguide/tzdb.html">"Updating the time zone database"</a> section in the user guide.</p>

<h2>Pre-release branching</h2>

<p>Before building the first release with a given minor version number (i.e. 1.0.0,
1.1.0, or more typically, a -beta or -rc version of the same), we'll need to
branch. New user-visible functionality is introduced with a new minor version
number (per the <a href="http://semver.org">Semantic versioning</a> spec).</p>

<p>The branching model used by Noda Time is the Subversion-style backport model.
In brief:</p>

<ul>
<li>feature development is carried out on the default branch</li>
<li>named branches (called '1.0.x', '1.1.x', etc) are used for release lines</li>
<li>fixes are typically backported to the earlier branches where necessary
(typically using <code>hg graft</code>).</li>
</ul>

<p>Note the difference between the format of names used for tags ('1.0.0-beta2',
'1.0.0') and those used for branches ('1.0.x'). Mercurial will allow both to be
used as revision specifiers, so it is important that they do not collide.</p>

<h3>Branch-specific changes</h3>

<p>The only change that needs to be made to the branch after creation is to
remove the <code>&lt;Preliminary/&gt;</code> tag from the Sandcastle project file; see e.g.
<a href="http://code.google.com/p/noda-time/issues/detail?id=102">issue 102</a>.</p>

<h2>Making the release</h2>

<p>Switch to the correct branch (e.g. <code>1.0.x</code>).</p>

<p>Update the version number by building the tools solution and then running the <code>SetVersion</code> tool:</p>

<pre class="prettyprint"><code>msbuild src\NodaTime-Tools.sln
src\NodaTime.Tools.SetVersion\bin\debug\SetVersion 1.2.3-beta4
</code></pre>

<blockquote>
  <p>This will update the following AssemblyInfo files and NuGet package specs to include the
  version number you are building:</p>
  
  <ul>
  <li><code>src/NodaTime/Properties/AssemblyInfo.cs</code></li>
  <li><code>src/NodaTime.Testing/Properties/AssemblyInfo.cs</code></li>
  <li><code>src/NodaTime/NodaTime.nuspec</code></li>
  <li><code>src/NodaTime.Testing/NodaTime.Testing.nuspec</code></li>
  </ul>
  
  <p>The various versions will be set according to the following scheme. Suppose
  we were building version 1.2.3-beta4, then:</p>
  
  <ul>
  <li>In the NuGet package specs, <code>&lt;version&gt;</code> should contain the version number
  ('1.2.3-beta4'). The <code>&lt;dependency&gt;</code> element in <code>NodaTime.Testing.nuspec</code>
  should reference the <em>initial release</em> for the major/minor version
  (i.e. '1.2.0') for stable versions, or the full version for
  pre-release versions.</li>
  <li>In the AssemblyInfo files, <code>AssemblyVersion</code> should be set to just the
  major/minor version ('1.2'). <code>AssemblyFileVersion</code> should be set to the
  major, minor, and patch version ('1.2.3'), and <code>AssemblyInformationalVersion</code>
  should be set to the version number ('1.2.3-beta4'). (See <a href="http://stackoverflow.com/a/65062">this Stack
  Overflow post</a> for more information about how these are
  used.)</li>
  </ul>
</blockquote>

<p>Add the current date and TZDB version to the version history in
<code>src/docs/userguide/markdown/versions.txt</code> and regenerate all documentation.</p>

<p>Commit the above, then tag that commit:</p>

<pre class="prettyprint"><code>hg tag 1.0.0-beta1
</code></pre>

<p>Switch back to the default branch and update the version history in that branch to match the changes applied to the release branch.</p>

<p>Push these changes to Google Code.</p>

<h2>Building the release artifacts</h2>

<p>First, <em>create a new clone for building the release</em>. Doing this avoids the
need to worry about ignored files and local changes making their way into
the archives.</p>

<p>Use the <code>buildrelease</code> batch file to build all the release artifacts:</p>

<pre class="prettyprint"><code>buildrelease 1.0.0-beta1
</code></pre>

<p>This will create:</p>

<ul>
<li>A zip file of pristine sources (e.g. <code>NodaTime-1.0.0-beta1-src.zip</code>)</li>
<li>A zip file for binary distribution (e.g. <code>NodaTime-1.0.0-beta1.zip</code>)</li>
<li>NuGet packages (in the <code>nuget</code> directory)</li>
</ul>

<p>(See <code>buildrelease.bat</code> for details.)</p>

<h2>Publishing the artifacts</h2>

<p>Upload the source and release zipfiles to the
<a href="http://code.google.com/p/noda-time/downloads/list">Google Code project</a>.
Use the <code>Type-Source</code> label for the source zipfile, and the <code>Type-Archive</code> and
<code>Featured</code> labels for the release zipfile.  Remove <code>Featured</code> from the previous
binary zipfile.</p>

<p>Update the version number and the links on the front page to point to the new
downloads.</p>

<p>Upload the two NuGet packages to nuget.org:</p>

<pre class="prettyprint"><code>nuget push NodaTime.1.0.0-beta1.nupkg
nuget push NodaTime.Testing.1.0.0-beta1.nupkg
</code></pre>

<h2>Announcing the release</h2>

<p>Post to the mailing list, blog, etc.</p>

<h2>Post-release branch updates</h2>

<p>If this release required the creation of a new branch, then the following files
on the <em>default</em> branch should be updated to bump (at least) the minor version
number (and <code>NodaTime.Testing</code> dependency version), per the scheme above:</p>

<ul>
<li><code>src/NodaTime/Properties/AssemblyInfo.cs</code></li>
<li><code>src/NodaTime.Testing/Properties/AssemblyInfo.cs</code></li>
<li><code>src/NodaTime/NodaTime.nuspec</code></li>
<li><code>src/NodaTime.Testing/NodaTime.Testing.nuspec</code></li>
</ul>

<p>The version number string should be of the form <code>1.1.0-dev</code>.</p>


    <div class="footer navigation">
      <p class="prev"><a href="coding-conventions.html">Coding conventions</a>&nbsp;</p>
      <p class="next">&nbsp;<a href="tzdb-file-format.html">Time zone database file format</a></p>
      <p class="navtitle">Version 1.2.0-dev</p>
      <div style="clear:both;"></div>
    </div>
  </body>
</html>
